home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / c / wgt35.zip / WSPR.DOC < prev    next >
Text File  |  1993-01-28  |  9KB  |  303 lines
  1.             WSPR.LIB Documentation
  2.             ~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4.     The WordUp Graphics Toolkit Version 3.5 includes a special
  5. library for sprites.  The library allows you to edit sprites using 
  6. the WGT Sprite Creator, load them in your program, and display
  7. them on the screen.  The best part about the sprites is you can
  8. set up movement and animation sequences and the library will handle
  9. everything for you.  
  10.  
  11.  
  12. Using WSPR.LIB
  13. ~~~~~~~~~~~~~~
  14.     To use the library, you must also link wgt.lib, and include
  15. wgt.h and wspr.h.  The library needs a lot of memory so make sure
  16. you have lots, and set the program heap size in the Options\Debugger
  17. menu.
  18.  
  19.  
  20.  
  21.  
  22.             Sprite Procedures
  23.             ~~~~~~~~~~~~~~~~~
  24.  
  25. wloadpsprites and wfreesprites have been moved to the main library.
  26.  
  27. void initspr(void);
  28.  
  29.     Initializes sprite library.
  30.     Sets up internal variables, and makes a virtual screen
  31.     called 'spritescreen'.
  32.  
  33.     Assumes you have loaded sprites into an array called 'sprites'.
  34.     You must call it sprites for these routines to work.
  35.  
  36.     You must call this after you load in sprites using wloadsprites.
  37.     If you need to call this more than once in a program, you
  38.     must free the virtual screen by wfreeblock(spritescreen).
  39.  
  40.     Example usage:
  41.         initspr();
  42.  
  43.  
  44. --------------------------------------------------------------------------
  45.  
  46.  
  47. void spriteon(int spritenum,int x coord,int y coord,int arrnumber);
  48.  
  49.     Turns a sprite on at the coordinates, using the arrnumber block
  50. from the sprites array.  Arrnumber is the same as the sprite numbers in
  51. the WGT Sprite Creator.  Spritenum can range from 1 to 40.  This means you
  52. can have 40 sprites on the screen at once.  
  53.     Each call to spriteon must be followed later in the program by
  54. a spriteoff.  Do not call spriteon using the same spritenum twice in a row
  55. or the computer may hang. You must turn the sprite off and back on again.
  56.  
  57.     Example usage:
  58.         spriteon(1,160,100,3);
  59.  
  60.  
  61. --------------------------------------------------------------------------
  62.  
  63.  
  64. void spriteoff(int spritenum);
  65.  
  66.     Turns off a sprite. See above.
  67.  
  68.     Example usage:
  69.         spriteoff(3);
  70.  
  71.  
  72. --------------------------------------------------------------------------
  73.  
  74.  
  75. void animate(int spritenum,char *animation sequence);
  76.  
  77.     Sets up animation for a sprite.  Spritenum is the sprite number
  78. to animate.  The string you must pass takes the following form:
  79.  
  80.     "(arrnumber,delay)(arrnumber2,delay2)R"
  81.  
  82. Between each set of brackets is the information required to animate the
  83. sprite.  The first number is the sprite array number, and the second is
  84. how long that sprite number is displayed. You then make another set and use
  85. different sprite numbers and delays.  If you place a CAPITAL R at the end
  86. of the string, the animation will (R)epeat itself when it gets to the end.
  87. If you leave the R out, the animation will occur once, and stop.
  88. You can have 40 sets for animation.
  89.  
  90. For example: To animate sprite number one between two sprites, and repeat:
  91.  
  92.     Animate(1,"(1,0)(2,0)R");
  93.         ^   ^    ^   ^
  94.         |   |    |   | R repeats the sequence
  95.         |   |    |
  96.         |   |    |Second sprite shown is number 2, with no delay
  97.         |   |
  98. Sprite to animate   |First sprite shown is number 1, with no delay
  99.  
  100. After calling this procedure, you must turn the animation on with animon.
  101.  
  102.     Example usage:
  103.         Animate(4,"(5,12)(69,0)(200,100)");
  104.  
  105.  
  106. --------------------------------------------------------------------------
  107.  
  108.  
  109. void animon(int spritenum);
  110.  
  111.     Turns animation on for the sprite.  See above for setting animation.
  112.  
  113.     Example usage:
  114.         animon(3);
  115.  
  116.  
  117. --------------------------------------------------------------------------
  118.  
  119.  
  120. void animoff(int spritenum);
  121.  
  122.     Freezes animation for the sprite.
  123.  
  124.     Example usage:
  125.         animoff(3);
  126.  
  127.  
  128. --------------------------------------------------------------------------
  129.  
  130.  
  131. void movex(int spritenum,char *movement sequence);
  132.  
  133.     Sets up horizontal movement for a sprite.
  134.     Works the similar to animate only there are 3 numbers in each set.
  135.     You can have 15 sets for movement.
  136.  
  137.     movex(3,"(1,50,1)(-1,50,0)R");
  138.  
  139.     The first number in the set is added to the current x coordinate
  140. of the sprite.  Therefore if the sprite is at 100,50 on the screen, and
  141. you make the number a 5, the sprite will move to 105,50.  This number can
  142. be anything, so you can have the sprite move right (positive numbers),
  143. left (negative numbers) or nowhere (zero).
  144.  
  145.     The second number in the set is the number of times to move the
  146. sprite before going on to the next set.  Always >0!
  147.  
  148.     The third number in the set is the delay for each time the sprite
  149. moves. Try using 0 at first and increase it to slow the sprites down.
  150.  
  151.     If the set was (1,50,1), then the sprite would move to the right
  152. one pixel, 50 times, with a delay of 1 for each move.  Then the next set
  153. would be activated. If you have a CAPITAL R at the end of the string,
  154. the movement will repeat.
  155.  
  156.     For example, to make sprite 2 move back and forth on the screen
  157. continuously:
  158.     movex(2,"(1,200,0)(-1,200,0)R");
  159.  
  160.     To make a sprite move from the left side to the right, and jump
  161. back to the left again:
  162.  
  163.     movex(2,"(1,319,0)(-319,1,0)R");
  164.                ^
  165.                | This moves the sprite 319 pixels to the left!
  166.  
  167.  
  168. --------------------------------------------------------------------------
  169.  
  170.  
  171. void movey(int spritenum,char *movement sequence);
  172.  
  173.     Sets up vertical movement for a sprite.
  174.     Exactly the same a movex. See above.
  175.  
  176.  
  177. --------------------------------------------------------------------------
  178.  
  179.  
  180. void movexon(int spritenum);
  181.  
  182.     Turns horizontal movement for a sprite on.
  183.  
  184.     Example usage:
  185.         movexon(3);
  186.  
  187.  
  188. --------------------------------------------------------------------------
  189.  
  190.  
  191. void movexoff(int spritenum);
  192.  
  193.     Turns horizontal movement for a sprite off.
  194.  
  195.     Example usage:
  196.         movexoff(3);
  197.  
  198.  
  199. --------------------------------------------------------------------------
  200.  
  201.  
  202. void moveyon(int spritenum);
  203.  
  204.     Turns vertical movement for a sprite on.
  205.  
  206.     Example usage:
  207.         moveyon(3);
  208.  
  209.  
  210. --------------------------------------------------------------------------
  211.  
  212.  
  213. void moveyoff(int spritenum);
  214.  
  215.     Turns vertical movement for a sprite off.
  216.  
  217.     Example usage:
  218.         moveyoff(3);
  219.  
  220.  
  221. --------------------------------------------------------------------------
  222.  
  223.  
  224. int overlap(int spritenum 1,int spritenum 2);
  225.  
  226.     Tests if two sprites overlap each other on the screen.
  227.     Returns 1 if they are overlapping.
  228.     (Used for detecting collisions)
  229.  
  230. --------------------------------------------------------------------------
  231.  
  232.  
  233.  
  234. **************************************************************************
  235.  
  236.  
  237. The sprite library uses the following variables:
  238.  
  239. int spon=15;        - the highest sprite number used in your program
  240. int spclip=1;        - 0 means sprite clipping is off
  241.              (might hang computer is it is off)
  242. block spritescreen;        - the virtual screen used as a background
  243.  
  244.  
  245. A large structure contains all data about the sprites:
  246.  
  247. typedef struct {
  248.       int num;           // sprite number to show on screen
  249.       int x;                   // x coord
  250.       int y;                   // y coord
  251.       int ox;                   // last x coord
  252.       int oy;                   // last y coord
  253.       unsigned char on;               // sprite is on?
  254.       int maxx;                   // area on screen to copy
  255.       int maxy;                   // Upper left and
  256.       int minx;                        // Bottom right corners of box
  257.       int miny;                        // to copy.
  258.       block old;                       // old block (stores what was
  259.                               behind sprite)
  260.  
  261.       char animon;               // animation on?
  262.       int anm[41];                     // number of animation
  263.       unsigned char ans[41];           // delay for animations
  264.       char curan;               // current animation
  265.       unsigned char delcnt;           // delay count
  266.  
  267.       char movexon;               // x movement on?
  268.       int mvx[16];               // direction to move
  269.       int mvn[16];               // number of times to move
  270.       unsigned char mvxs[16];           // delay for movement
  271.       char curxmove;               // current x move
  272.       int curmnx;               // number of times moved already
  273.       unsigned char mvxcnt;           // delay count
  274.  
  275.       char moveyon;               // y movement on?
  276.       int mvy[16];               // direction to move
  277.       int mvny[16];               // number of times to move
  278.       unsigned char mvys[16];           // delay for movement
  279.       char curymove;               // current y move
  280.       int curmny;               // number of times moved already
  281.       unsigned char mvycnt;            // delay count
  282.  
  283.       } sprit;
  284. sprit s[40];
  285.  
  286. You will probably not need to change any of these.  There are a few
  287. applications however.  
  288.  
  289. If you need to store the movements or animations as integers, it will be
  290. a pain converting the numbers into a correct string to pass to the animate
  291. command, therefore you can just put them directly into the arrays yourself.
  292.  
  293. If you draw something other than a sprite on the virtual screen, you will
  294. need to copy more of the screen to the visual page.  Therefore change the
  295. minx,miny,maxx,maxy variables of a sprite that is on to the coordinates
  296. of the area you need to copy.  See breakout.c for an example of this.
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.